Skip to content

Make CLI lesson output easier to read - #227

Merged
skovranek merged 2 commits into
mainfrom
8533_ms_feat_readable_cli_output
Nov 17, 2026
Merged

skovranek merged 2 commits into
mainfrom
8533_ms_feat_readable_cli_output

Conversation

@skovranek

@skovranek skovranek commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

resolves bootdotdev/go-api-gate#8533.

Improve CLI output readability with numbered step headings, clearer grouping, and configurable colors.

  • Keep lesson headers visible in the final report.
  • Show commands, requests, and actual output during runs without checks or grading.
  • Keep successful submissions compact, with detailed output for failures or --verbose.
  • Show expected and actual values for checks, including JSON values.
  • Show failure details beside the responsible check or step.
  • Use semantic color settings with coordinated defaults.
  • Add local-test --run for previewing execution without grading.

Color configuration

Colors can be configured through bootdev config colors or the config file.

  • Rename gray, red, green, magenta, and yellow to secondary, fail, pass, accent, and warning.
  • Add header, subheader, and information.
  • Support ANSI palette indexes and hex colors.

Existing color-name settings must be renamed to preserve custom colors.

Local CLI screenshots

These examples use local command fixtures. Runs show what happened; submissions also show how the checks were graded.

Run — zero exit code

The command completes successfully and its output is shown.

Run — zero exit code

Run — nonzero exit code

The exit code is visible without a grading label.

Run — nonzero exit code

Passing submission — default

Successful steps are summarized.

Passing submission — default

Passing submission — expanded steps

With --verbose, numbered checks appear before each step’s output.

Show expanded steps

Passing submission — expanded steps

Failing submission — default

The failed step shows the expected and actual exit codes. Later steps are hidden.

Failing submission — default

Failing submission — expanded steps

With --verbose, later steps show their output, and unevaluated checks have no grading label.

Show expanded steps

Failing submission — expanded steps

@skovranek
skovranek force-pushed the 8533_ms_feat_readable_cli_output branch from fc48dc2 to 7464fc0 Compare November 10, 2026 16:45

@squashd squashd left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this looks awesome — tokyo night for the people!

mostly nits/suggestions, and one smol regression. i'm assuming the images will get removed 🙏

Comment thread render/header.go
fmt.Fprintln(&str, lipgloss.NewStyle().Bold(true).Render(context.LessonTitle))
if context.BaseURL != "" {
fmt.Fprintf(&str, "%s %s\n", secondaryStyle.Render("Target:"), context.BaseURL)
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think we could add part of the override warning here? I like the simplification, just worried we'll have students who forgot they'd added an override

		fmt.Printf("Using overridden base_url: %v\n", overrideBaseURL)
		fmt.Printf("You can reset to the default with `bootdev config base_url --reset`\n\n")

@skovranek skovranek Nov 16, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call. Keeping it the same as before

Comment thread render/step.go Outdated
Comment on lines +61 to +64
heading := "Checks"
if isSubmit {
heading = "Checks not evaluated"
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we omit actual if it isn't evaluated?

Screenshot 2026-11-12 at 17 50 03

@skovranek skovranek Nov 16, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes omit actual if no actual exists

Comment thread render/http.go Outdated
func printHTTPRequestResult(result api.HTTPRequestResult) string {
if result.Err != "" {
return fmt.Sprintf(" Err: %v\n\n", result.Err)
return fmt.Sprintf("%s\n%s\n", warningStyle.Render("Request error"), indentOutput(result.Err, 2))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is "Request" meant as the name of the step type? I wonder if this could make someone think they didn't get the request (but it waws their response that was malformed)

@skovranek skovranek Nov 16, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call, request makes no sense. Now the errors say where the error occured: request, http connection, or response

Comment thread render/view.go
Comment on lines +65 to +69
if showAllDetails || (failed && m.finalized) {
dividerWidth := m.terminalWidth
if dividerWidth <= 0 {
dividerWidth = 80
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: The step title and command / request get repeated now. Do you think the summary could be shorter (maybe if not verbose)?

Screenshot 2026-11-12 at 18 07 51

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

keeping the failed step expanded but no second summary

Comment thread render/json.go Outdated
default:
return ""
}
expectedJSON, err := json.Marshal(expected)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

clanker pointed out this would now be html-escaped

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed with SetEscapeHTML(false) when formatting the selected JSON expected/actual values, so HTML characters remain readable.

Comment thread render/variables.go Outdated
Comment on lines +30 to +32
if title == "Variables Missing" {
headingText = warningStyle.Render(title + ":")
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: matching on the string feels iffy

@skovranek skovranek Nov 16, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ew thank you

Comment thread render/step.go Outdated
Comment on lines +45 to +49
check := renderCheck(step, index, status)
check = renderStatus(status) + strings.TrimPrefix(check, status)
check = strings.ReplaceAll(check, "\n Expected:", "\n "+secondaryStyle.Render("Expected:"))
check = strings.ReplaceAll(check, "\n Actual:", "\n "+secondaryStyle.Render("Actual:"))
fmt.Fprintf(&str, "\n%s\n", indentOutput(check, 2))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

splitting on a string and reconstructing it for rendering feels a bit brittle. could it be set where it's built?

@skovranek skovranek Nov 16, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yikes

@skovranek
skovranek force-pushed the 8533_ms_feat_readable_cli_output branch 2 times, most recently from 9d7ed5c to d5dac21 Compare November 16, 2026 03:05
@skovranek
skovranek requested a balanced review from Copilot November 16, 2026 03:05

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Relative lesson paths lose chapter/lesson numbers and can produce a dot as the title when no README heading exists, making headers depend on how the path is supplied.

1 open issue
What changed in this PR

This PR improves lesson execution reports in the CLI, making runs easier to inspect and submissions easier to scan.

Changes:

  • Adds persistent lesson headers, numbered steps, grouped diagnostics, and expected/actual values for supported checks.
  • Introduces semantic color settings with coordinated defaults and updated configuration documentation.
  • Adds local-test --run for ungraded previews and expands output regression coverage.
File Description
version.txt Bumps the version to v1.33.0.
render/​view.go Integrates numbered steps, detailed output, and failure summaries.
render/​view_test.go Covers numbering, failure summaries, and ungraded output.
render/​variables.go Adds styled headings to variable sections.
render/​variables_test.go Updates tests for styled variable sections.
render/​step.go Adds grouped step details and check-value rendering.
render/​step_test.go Tests diagnostic grouping and run/submit differences.
render/​render.go Initializes semantic styles and accepts lesson context.
render/​palette.go Defines coordinated default colors.
render/​models.go Stores detail labels, lesson context, and terminal width.
render/​json.go Formats expected and actual JSON check values.
render/​json_test.go Covers JSON diagnostics, fallbacks, and truncation.
render/​http.go Groups HTTP diagnostics and preserves JSON formatting.
render/​header.go Renders persistent lesson and base-URL headers.
render/​header_test.go Tests header persistence and optional context.
README.md Documents semantic color configuration.
main_test.go Extends redirected-output tests to ungraded previews.
cmd/​submit.go Passes lesson context to the renderer.
cmd/​localtest.go Adds preview mode, local headers, and duplicate-error suppression.
cmd/​localtest_test.go Tests local lesson title and numbering discovery.
cmd/​configure.go Registers semantic color defaults.
client/​lessons.go Adds non-serialized HTTP error categories.
checks/​local.go Uses the exported JSON-path lookup helper.
checks/​jq.go Exports JSON-path lookup for rendering diagnostics.
checks/​jq_test.go Updates coverage for the exported helper.
checks/​http.go Categorizes request, exchange, and response errors.
checks/​http_test.go Tests HTTP error categorization.

Review effort: Balanced

Comment thread cmd/localtest.go
}

func localRunContext(path string) render.RunContext {
manifestPath := filepath.Clean(path)
@skovranek
skovranek force-pushed the 8533_ms_feat_readable_cli_output branch 3 times, most recently from c96861e to a51fcf7 Compare November 17, 2026 19:40
Clarify numbered checks and simplify failure output

Preserve skipped step details and show submission errors

Preserve grading diagnostics beneath failed checks

Preserve unmatched grading errors and bound diagnostics

changes

test changes
@skovranek
skovranek force-pushed the 8533_ms_feat_readable_cli_output branch from a51fcf7 to eda2349 Compare November 17, 2026 20:26
@skovranek
skovranek merged commit 113e9d5 into main Nov 17, 2026
1 check passed
@skovranek
skovranek deleted the 8533_ms_feat_readable_cli_output branch November 17, 2026 20:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants